home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 002 / fgrep145.arc / FGREP.DOC < prev   
Text File  |  1987-05-07  |  10KB  |  231 lines
  1.                                   fgrep 1.45
  2.                                   ----------
  3.  
  4.         "|" denotes items that are new/changed in the current version.
  5.         Note that some previous versions were simply called "grep".
  6.  
  7.         Purpose
  8.         -------
  9.  
  10.         Fgrep (Fast GREP) is a small utility that can be used to find
  11.         specific strings of characters in ASCII text files.  String
  12.         search capabilities are not extensive (no regular expressions),
  13.         but fgrep is small and quite fast (on a standard PC equipped
  14.         with a fairly slow fixed disk, fgrep can perform a case and
  15.         spacing insensitive search of 30 files totalling over 1/3
  16.         megabyte of text in about 22 seconds).  Fgrep is intended to
  17.         replace DOS's FIND filter with something faster and more
  18.         flexible.
  19.  
  20.         UNIX people: we fully realize that this isn't the grep with
  21.         which you are familiar.  However, the name serves to point
  22.         people in the right direction.
  23.  
  24.         Using fgrep
  25.         -----------
  26.  
  27.         Fgrep's syntax is
  28.  
  29.                 fgrep [-cfnvwse01] target {file}
  30.  
  31.         The -switches are discussed below.
  32.  
  33.      |  The target is the string of characters for which you are
  34.      |  searching.  It may need to be bracketed by a pair of
  35.      |  non-alphanumeric delimiters.  The target should be delimited if:
  36.      |
  37.      |      -- it contains spaces or tabs
  38.      |      -- it begins with a non-alphanumeric character
  39.      |      -- it contains the DOS redirection characters < > |.
  40.      |
  41.      |  In the last case, the string MUST be delimited by double quotes
  42.      |  ("), otherwise DOS will interpret it as redirection.
  43.      |
  44.      |  Examples of targets:
  45.      |
  46.      |          mov
  47.      |          ax
  48.      |          /mov ax/        (contains a space)
  49.      |          '/7'            (begins with non-alphanumeric)
  50.      |          "f->x"          (contains ">", must use double quotes)
  51.      |
  52.      |  It is always OK to delimit a string, even if delimiters are
  53.      |  unnecessary.
  54.  
  55.         The string may include one or more "?" wildcards.  The ? will
  56.         match any single non-null character in the file.  E.g., "[?i]"
  57.         will match "[si]", "[di]", etc., but not "[i]".
  58.  
  59.         The list of files may include wild cards.  Here are some
  60.         examples of fgrep use:
  61.  
  62.                 fgrep  -c  "include foo.c"  *.c
  63.                 fgrep abcd? filea.ext fileb.ext filec.ext
  64.                 fgrep -1f 'call fido' a:\masm\*.asm  b:*.asm
  65.                 fgrep ax *.asm
  66.  
  67.         If no file is specified, input will be taken from standard
  68.         input, allowing redirection and piping:
  69.  
  70.                 arc p somefile foo.txt | fgrep somestring
  71.  
  72.         will display occurrences of "somestring" in the file archived as
  73.         foo.txt in somefile.arc.
  74.  
  75.  
  76.         Output
  77.         ------
  78.  
  79.         Fgrep's screen output looks like this:
  80.  
  81.                 **File <filename>
  82.                 [text of lines containing string]
  83.                 **File <filename>
  84.                 [text of lines containing string]
  85.  
  86.         All useful output is sent to the standard output device, so it
  87.         may be piped to other programs or redirected to file:
  88.  
  89.                 fgrep target filea | yourprog
  90.                 fgrep target filea > test.txt
  91.  
  92.         Error messages and the program logo will appear always appear on
  93.         the console device, and will never appear in redirected or piped
  94.         output.
  95.  
  96.         Fgrep always returns an errorlevel to the operating system.  It
  97.         will be one of:
  98.  
  99.             0:   String not found in any file
  100.             1:   String found in at least one file
  101.             255: Error (file read error, or bad parameter)
  102.  
  103.  
  104.         Switches
  105.         --------
  106.  
  107.         The -c switch makes the search case sensitive ("String" will not
  108.         match "string" or "STRING").  Normally, fgrep ignores case.
  109.  
  110.         The -v switch provides a reVerse or negative search.  That is,
  111.         all lines that do NOT contain the specified string are
  112.         displayed.  This provides a handy way to get rid of lines
  113.         containing specified text.  Suppose, for example, that you have
  114.         a file containing a list of file names, and you are interested
  115.         in all files EXCEPT those that contain a '$' in the name
  116.         (perhaps they are temporary files):
  117.  
  118.             fgrep -v "$" filename
  119.  
  120.         The -f switch causes the "**File" header lines to be displayed
  121.         only for those files that contain the search string.
  122.  
  123.      |  The -l (alpha L) switch adds line numbers to fgrep's output.
  124.  
  125.         The -s switch suppresses the "**File" header lines in the
  126.         output.
  127.  
  128.         The -w switch indicates that white space (blanks and tabs)
  129.         is not significant.  White space in both the search string
  130.         and the input file will be ignored.  If -w is specified, the
  131.         wildcard character (?) will match any nonblank character.
  132.  
  133.         The -0 switch ("0" text lines) suppresses the display of lines
  134.         of text containing the specified string.  fgrep will skip
  135.         immediately to the next file when the string is found.
  136.  
  137.         The -1 switch ("1" text line) specifies that only the first line
  138.         containing containing the specified string in each file will be
  139.         displayed. fgrep will then skip immediately to the next file.
  140.  
  141.         The -e switch specifies that ONLY an errorlevel is to be
  142.         returned.  There will be no display at all.  This is equivalent
  143.         to the combination -s0.
  144.  
  145.  
  146.         Notes
  147.         -----
  148.  
  149.         1. The -f and -s switches are mutually exclusive.  If both are
  150.         specified, the last one will be effective.
  151.  
  152.         2. If you specify the -e switch, fgrep will stop processing as
  153.         soon as a nonzero errorlevel is determined.  The -e switch is
  154.         really designed to enable other programs to determine whether or
  155.         not a specific file contains a specific string in as little time
  156.         as possible.  For example, here's an algorithm that will quickly
  157.         'touch' all files that do NOT contain a specified string:
  158.  
  159.                 for file in (*.*) do
  160.                     fgrep -e "string" file
  161.                     if errorlevel < 1 then touch file
  162.                 end
  163.  
  164.         3. The -s switch is automatically set when input is taken from
  165.         standard input.
  166.  
  167.         4. fgrep optimizes the combination -s0 (suppress headers, no
  168.         text) to a -e.
  169.  
  170.         5. If you just want to know which files contain a string, use -0;
  171.         it saves time because the rest of the file (after the first hit)
  172.         is skipped.  The combination -0f is particularly efficient
  173.         for this as it will simply display a list of files that contain
  174.         the string.
  175.  
  176.  
  177.         Version 1.45
  178.         ------------
  179.         We found a few areas that could be made more efficient.  This
  180.         version can be as much as 25-30% faster than version 1.40.
  181.  
  182.         The -L (line numbers) option was added, and improvements made to
  183.         parameter parsing such that delimiters are not always necessary.
  184.  
  185.  
  186.         Copyright/License/Warranty
  187.         --------------------------
  188.  
  189.         This document and the program file FGREP.EXE ("the software")
  190.         are copyrighted by the author.  The copyright owner hereby
  191.         licenses you to: use the software; make as many copies of the
  192.         program and documentation as you wish; give such copies to
  193.         anyone; and distribute the software and documentation via
  194.         electronic means.  There is no charge for any of the above.
  195.  
  196.         However, you are specifically prohibited from charging, or
  197.         requesting donations, for any such copies, however made; and
  198.         from distributing the software and/or documentation with
  199.         commercial products without prior permission.  An exception is
  200.         granted to not-for-profit user's groups, which are authorized to
  201.         charge a small fee (not to exceed $7) for materials, handling,
  202.         postage, and general overhead.  NO FOR-PROFIT ORGANIZATION IS
  203.         AUTHORIZED TO CHARGE ANY AMOUNT FOR DISTRIBUTION OF COPIES OF
  204.         THE SOFTWARE OR DOCUMENTATION, OR TO INCLUDE COPIES OF THE
  205.         SOFTWARE OR DOCUMENTATION WITH SALES OF THEIR OWN PRODUCTS.
  206.  
  207.         THIS INCLUDES A SPECIFIC PROHIBITION AGAINST FOR-PROFIT
  208.         ORGANIZATIONS DISTRIBUTING THE SOFTWARE, EITHER ALONE OR WITH
  209.         OTHER SOFTWARE, AND CHARGING A "HANDLING" OR "MATERIALS" FEE OR
  210.         ANY OTHER SUCH FEE FOR THE DISTRIBUTION.  NO FOR-PROFIT
  211.         ORGANIZATION IS AUTHORIZED TO INCLUDE THE SOFTWARE ON ANY MEDIA
  212.         FOR WHICH MONEY IS CHARGED.  PERIOD.
  213.  
  214.         No copy of the software may be distributed or given away without
  215.         this document; and this notice must not be removed.
  216.  
  217.         There is no warranty of any kind, and the copyright owner is not
  218.         liable for damages of any kind.  By using this free software,
  219.         you agree to this.
  220.  
  221.         The software and documentation are:
  222.  
  223.                        Copyright (C) 1985, 1986, 1987 by
  224.                             Christopher J. Dunford
  225.                            10057-2 Windstream Drive
  226.                            Columbia, Maryland 21044
  227.                                 (301) 992-9371
  228.  
  229.         Comments to Chris Dunford [CIS 76703,2002].  For personal use
  230.         only.  Not for sale.
  231.